home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib / tcl / CrtCommand.man < prev    next >
Encoding:
Text File  |  1992-08-07  |  8.6 KB  |  300 lines
  1. '\"
  2. '\" Copyright 1989 Regents of the University of California
  3. '\" Permission to use, copy, modify, and distribute this
  4. '\" documentation for any purpose and without fee is hereby
  5. '\" granted, provided that this notice appears in all copies.
  6. '\" The University of California makes no representations about
  7. '\" the suitability of this material for any purpose.  It is
  8. '\" provided "as is" without express or implied warranty.
  9. '\" 
  10. '\" $Header: /user6/ouster/tcl/man/RCS/CrtCommand.man,v 1.6 91/12/06 10:34:39 ouster Exp $ SPRITE (Berkeley)
  11. '\" 
  12. .\" The definitions below are for supplemental macros used in Sprite
  13. .\" manual entries.
  14. .\"
  15. .\" .HS name section [date [version]]
  16. .\"    Replacement for .TH in other man pages.  See below for valid
  17. .\"    section names.
  18. .\"
  19. .\" .AP type name in/out [indent]
  20. .\"    Start paragraph describing an argument to a library procedure.
  21. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  22. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  23. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  24. .\"    needed;  use .AS below instead)
  25. .\"
  26. .\" .AS [type [name]]
  27. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  28. .\"    name are examples of largest possible arguments that will be passed
  29. .\"    to .AP later.  If args are omitted, default tab stops are used.
  30. .\"
  31. .\" .BS
  32. .\"    Start box enclosure.  From here until next .BE, everything will be
  33. .\"    enclosed in one large box.
  34. .\"
  35. .\" .BE
  36. .\"    End of box enclosure.
  37. .\"
  38. .\" .VS
  39. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  40. .\"    of man pages.
  41. .\"
  42. .\" .VE
  43. .\"    End of vertical sidebar.
  44. .\"
  45. .\" .DS
  46. .\"    Begin an indented unfilled display.
  47. .\"
  48. .\" .DE
  49. .\"    End of indented unfilled display.
  50. .\"
  51. '\"    # Heading for Sprite man pages
  52. .de HS
  53. .if '\\$2'cmds'       .TH \\$1 1 \\$3 \\$4
  54. .if '\\$2'lib'        .TH \\$1 3 \\$3 \\$4
  55. .if '\\$2'tcl'        .TH \\$1 3 \\$3 \\$4
  56. .if '\\$2'tk'         .TH \\$1 3 \\$3 \\$4
  57. .if t .wh -1.3i ^B
  58. .nr ^l \\n(.l
  59. .ad b
  60. ..
  61. '\"    # Start an argument description
  62. .de AP
  63. .ie !"\\$4"" .TP \\$4
  64. .el \{\
  65. .   ie !"\\$2"" .TP \\n()Cu
  66. .   el          .TP 15
  67. .\}
  68. .ie !"\\$3"" \{\
  69. .ta \\n()Au \\n()Bu
  70. \&\\$1    \\fI\\$2\\fP    (\\$3)
  71. .\".b
  72. .\}
  73. .el \{\
  74. .br
  75. .ie !"\\$2"" \{\
  76. \&\\$1    \\fI\\$2\\fP
  77. .\}
  78. .el \{\
  79. \&\\fI\\$1\\fP
  80. .\}
  81. .\}
  82. ..
  83. '\"    # define tabbing values for .AP
  84. .de AS
  85. .nr )A 10n
  86. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  87. .nr )B \\n()Au+15n
  88. .\"
  89. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  90. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  91. ..
  92. '\"    # BS - start boxed text
  93. '\"    # ^y = starting y location
  94. '\"    # ^b = 1
  95. .de BS
  96. .br
  97. .mk ^y
  98. .nr ^b 1u
  99. .if n .nf
  100. .if n .ti 0
  101. .if n \l'\\n(.lu\(ul'
  102. .if n .fi
  103. ..
  104. '\"    # BE - end boxed text (draw box now)
  105. .de BE
  106. .nf
  107. .ti 0
  108. .mk ^t
  109. .ie n \l'\\n(^lu\(ul'
  110. .el \{\
  111. .\"    Draw four-sided box normally, but don't draw top of
  112. .\"    box if the box started on an earlier page.
  113. .ie !\\n(^b-1 \{\
  114. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  115. .\}
  116. .el \}\
  117. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  118. .\}
  119. .\}
  120. .fi
  121. .br
  122. .nr ^b 0
  123. ..
  124. '\"    # VS - start vertical sidebar
  125. '\"    # ^Y = starting y location
  126. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  127. .de VS
  128. .mk ^Y
  129. .ie n 'mc \s12\(br\s0
  130. .el .nr ^v 1u
  131. ..
  132. '\"    # VE - end of vertical sidebar
  133. .de VE
  134. .ie n 'mc
  135. .el \{\
  136. .ev 2
  137. .nf
  138. .ti 0
  139. .mk ^t
  140. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  141. .sp -1
  142. .fi
  143. .ev
  144. .\}
  145. .nr ^v 0
  146. ..
  147. '\"    # Special macro to handle page bottom:  finish off current
  148. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  149. '\"    # page bottom macro.
  150. .de ^B
  151. .ev 2
  152. 'ti 0
  153. 'nf
  154. .mk ^t
  155. .if \\n(^b \{\
  156. .\"    Draw three-sided box if this is the box's first page,
  157. .\"    draw two sides but no top otherwise.
  158. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  159. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  160. .\}
  161. .if \\n(^v \{\
  162. .nr ^x \\n(^tu+1v-\\n(^Yu
  163. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  164. .\}
  165. .bp
  166. 'fi
  167. .ev
  168. .if \\n(^b \{\
  169. .mk ^y
  170. .nr ^b 2
  171. .\}
  172. .if \\n(^v \{\
  173. .mk ^Y
  174. .\}
  175. ..
  176. '\"    # DS - begin display
  177. .de DS
  178. .RS
  179. .nf
  180. .sp
  181. ..
  182. '\"    # DE - end display
  183. .de DE
  184. .fi
  185. .RE
  186. .sp .5
  187. ..
  188. .HS Tcl_CreateCommand tcl
  189. .BS
  190. .SH NAME
  191. Tcl_CreateCommand, Tcl_DeleteCommand \- define application-specific command bindings
  192. .SH SYNOPSIS
  193. .nf
  194. \fB#include <tcl.h>\fR
  195. .sp
  196. \fBTcl_CreateCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR)
  197. .sp
  198. int
  199. \fBTcl_DeleteCommand\fR(\fIinterp, cmdName\fR)
  200. .SH ARGUMENTS
  201. .AS Tcl_CmdDeleteProc (*deleteProc)()
  202. .AP Tcl_Interp *interp in
  203. Interpreter in which to create new command.
  204. .AP char *cmdName in
  205. Name of command to create or delete.
  206. .AP Tcl_CmdProc *proc in
  207. Implementation of new command:  \fIproc\fR will be called whenever
  208. \fIcmdName\fR is invoked as a command.
  209. .AP ClientData clientData in
  210. Arbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR.
  211. .AP Tcl_CmdDeleteProc *deleteProc in
  212. Procedure to call before \fIcmdName\fR is deleted from the interpreter;
  213. allows for command-specific cleanup.  If NULL, then no procedure is
  214. called before the command is deleted.
  215. .BE
  216.  
  217. .SH DESCRIPTION
  218. .PP
  219. \fBTcl_CreateCommand\fR defines a new command in \fIinterp\fR and associates
  220. it with procedure \fIproc\fR such that whenever \fIcmdName\fR is
  221. invoked as a Tcl command (via a call to \fBTcl_Eval\fR) the Tcl interpreter
  222. will call \fIproc\fR
  223. to process the command.  If there is already a command \fIcmdName\fR
  224. associated with the interpreter, it is deleted.  \fIProc\fP should
  225. have arguments and result that match the type \fBTcl_CmdProc\fR:
  226. .nf
  227. .RS
  228. typedef int Tcl_CmdProc(
  229. .RS
  230. ClientData \fIclientData\fR,
  231. Tcl_Interp *\fIinterp\fR,
  232. int \fIargc\fR,
  233. char *\fIargv\fR[]);
  234. .RE
  235. .RE
  236. .fi
  237. When \fIproc\fR is invoked the \fIclientData\fP and \fIinterp\fR
  238. parameters will be copies of the \fIclientData\fP and \fIinterp\fR
  239. arguments given to \fBTcl_CreateCommand\fR.
  240. Typically, \fIclientData\fR points to an application-specific
  241. data structure that describes what to do when the command procedure
  242. is invoked.  \fIArgc\fR and \fIargv\fR describe the arguments to
  243. the command, \fIargc\fR giving the number of arguments (including
  244. the command name) and \fIargv\fR giving the values of the arguments
  245. as strings.  The \fIargv\fR array will contain \fIargc\fR+1 values;
  246. the first \fIargc\fR values point to the argument strings, and the
  247. last value is NULL.
  248. .PP
  249. \fIProc\fR must return an integer code that is either \fBTCL_OK\fR, \fBTCL_ERROR\fR,
  250. \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR.  See the Tcl overview man page
  251. for details on what these codes mean.  Most normal commands will only
  252. return \fBTCL_OK\fR or \fBTCL_ERROR\fR.  In addition, \fIproc\fR must set
  253. \fIinterp->result\fR to point to a string value;
  254. in the case of a \fBTCL_OK\fR return code this gives the result
  255. of the command, and in the case of \fBTCL_ERROR\fR it gives an error message.
  256. The \fBTcl_SetResult\fR procedure provides an easy interface for setting
  257. the return value;  for complete details on how the \fIinterp->result\fR
  258. field is managed, see the \fBTcl_Interp\fR man page.
  259. Before invoking a command procedure,
  260. \fBTcl_Eval\fR sets \fIinterp->result\fR to point to an empty string, so simple
  261. commands can return an empty result by doing nothing at all.
  262. .PP
  263. The contents of the \fIargv\fR array are copies made by the Tcl interpreter
  264. for the use of \fIproc\fR.  \fIProc\fR may alter any of the strings
  265. in \fIargv\fR.  However, the \fIargv\fR array
  266. is recycled as soon as \fIproc\fR returns, so \fIproc\fR must not set
  267. \fIinterp->result\fR to point anywhere within the \fIargv\fR values
  268. (call Tcl_SetResult
  269. with status \fBTCL_VOLATILE\fR if you want to return something from the
  270. \fIargv\fR array).
  271. .PP
  272. \fIDeleteProc\fR will be invoked when (if) \fIcmdName\fR is deleted.
  273. This can occur through a call to \fBTcl_DeleteCommand\fR or \fBTcl_DeleteInterp\fR,
  274. or by replacing \fIcmdName\fR in another call to Tcl_CreateCommand.
  275. \fIDeleteProc\fR is invoked before the command is deleted, and gives the
  276. application an opportunity to release any structures associated
  277. with the command.  \fIDeleteProc\fR should have arguments and
  278. result that match the type \fBTcl_CmdDeleteProc\fR:
  279. .nf
  280. .RS
  281. .sp
  282. typedef void Tcl_CmdDeleteProc(ClientData \fIclientData\fR);
  283. .sp
  284. .RE
  285. .fi
  286. The \fIclientData\fR argument will be the same as the \fIclientData\fR
  287. argument passed to \fBTcl_CreateCommand\fR.
  288. .PP
  289. \fBTcl_DeleteCommand\fR deletes a command from a command interpreter.
  290. Once the call completes, attempts to invoke \fIcmdName\fR in
  291. \fIinterp\fR will result in errors.
  292. If \fIcmdName\fR isn't bound as a command in \fIinterp\fR then
  293. \fBTcl_DeleteCommand\fR does nothing and returns -1;  otherwise
  294. it returns 0.
  295. There are no restrictions on \fIcmdName\fR:  it may refer to
  296. a built-in command, an application-specific command, or a Tcl procedure.
  297.  
  298. .SH KEYWORDS
  299. bind, command, create, delete, interpreter
  300.